org.globalplatform.contactless
Interface GPCLRegistryEntry

All Superinterfaces:

org.globalplatform.GPRegistryEntry, javacard.framework.Shareable

public interface GPCLRegistryEntry
extends org.globalplatform.GPRegistryEntry

Defines methods that manage the GlobalPlatform registry extension on contactless interface for an applet.

The caller shall use GPCLSystem.getGPCLRegistryEntry(AID) to retrieve an OPEN owned interface object.

All GPRegistryEntry of Application installed will be extended by this interface.

When the application represented by a GPCLRegistryEntry object is deleted, and Logically Deleted with References, then this GPCLRegistryEntry object shall be disabled and all its methods shall throw an javacard.framework.SystemException with reason code SystemException.ILLEGAL_USE.

The OPEN shall ensure that this GPCLRegistryEntry object can never be re-enabled, even if an application with the same AID as the deleted application (previously bound to this GPCLRegistryEntry object) is installed. An application holding a reference to a disabled GPCLRegistryEntry object should release it, as it has become useless and will only throw exceptions.

Note: Developer shall pay attention of CRELApplication , CLApplet and CRSApplication notifications when using the service interface. Thus it is strongly recommended do not call service provided by this interface under transaction.

See Also:

GPCLSystem.getGPCLRegistryEntry(AID)

Field Summary

static byte	IMPLICIT_SELECTION_TYPE_A Constant indicating that the application supports contactless protocol Type A for implicit selection
static byte	IMPLICIT_SELECTION_TYPE_B Constant indicating that the application supports contactless protocol Type B for implicit selection
static byte	IMPLICIT_SELECTION_TYPE_F Constant indicating that the application supports contactless protocol Type F for implicit selection
static short	INFO_CONTINUOUS_PROCESS The Application continuous processing is a Byte value 1 Continuous Processing 0 Interleave Processing
static short	INFO_COUNTER_UPDATE The GPCLentry update counter.
static short	INFO_DISCRETIONARY_DATA The requested information is discretionary data.
static short	INFO_DISPLAY_REQUIREMENT The GPCLRegistryEntry display on off requirement.
static short	INFO_FAMILY_IDENTIFIER The Application family identifier is a short value.
static short	INFO_IMPLICIT_SELECTION_PROTOCOLS The supported protocol Type A, Type B or / and Type F.
static short	INFO_LOGO The requested information is a LOGO.
static short	INFO_PROTOCOL_DATA_TYPE_A The requested information is the PROTOCOL_DATA_TYPE_A.
static short	INFO_PROTOCOL_DATA_TYPE_B The requested information is the PROTOCOL_DATA_TYPE_B.
static short	INFO_PROTOCOL_DATA_TYPE_F The requested information is the PROTOCOL_DATA_TYPE_F.
static short	INFO_URI The requested information is an URI.
static byte	PRIVILEGE_CONTACTLESS_ACTIVATION Contactless Activation privilege (18).
static byte	PRIVILEGE_CONTACTLESS_SELF_ACTIVATION Self Activation privilege (19).
static byte	STATE_CL_ACTIVATED Constant used to activate an applet on the contactless interface.
static byte	STATE_CL_DEACTIVATED Constant used to deactivate an applet on the contactless interface.
static byte	STATE_CL_NON_ACTIVATABLE Constant used to change the state of an applet to NON ACTIVATABLE over the contactless interface.

Fields inherited from interface org.globalplatform.GPRegistryEntry

PRIVILEGE_AUTHORIZED_MANAGEMENT, PRIVILEGE_CARD_LOCK, PRIVILEGE_CARD_RESET, PRIVILEGE_CARD_TERMINATE, PRIVILEGE_CIPHERED_LOAD_FILE_DATA_BLOCK, PRIVILEGE_CVM_MANAGEMENT, PRIVILEGE_DAP_VERIFICATION, PRIVILEGE_DELEGATED_MANAGEMENT, PRIVILEGE_FINAL_APPLICATION, PRIVILEGE_GLOBAL_DELETE, PRIVILEGE_GLOBAL_LOCK, PRIVILEGE_GLOBAL_REGISTRY, PRIVILEGE_GLOBAL_SERVICE, PRIVILEGE_MANDATED_DAP, PRIVILEGE_RECEIPT_GENERATION, PRIVILEGE_SECURITY_DOMAIN, PRIVILEGE_TOKEN_VERIFICATION, PRIVILEGE_TRUSTED_PATH

Method Summary

void	addToCRELApplicationList(byte[] baAID, short offsetAID, short lengthAID) This method add an AID to the CREL Application list referenced by this GPCLRegistryEntry
void	addToGroupAuthorizationList(byte[] baAID, short offsetAID, short lengthAID) This method is used to add an AID to the Group Authorization list.
byte	getCLState() This method returns the contactless life cycle state of application.
short	getInfo(byte[] buffer, short offset, short info) Returns the contents of the Application Information entry in the GlobalPlatform registry.
GPCLRegistryEntry	getNextConflictingApplication(GPCLRegistryEntry oEntry) This method allows iteration over the currently activated contactless applets that would conflict if the applet associated with this entry was activated.
GPCLRegistryEntry	getNextCRELApplication(GPCLRegistryEntry oEntry) Retrieve the list of CREL applications referenced by this GPCLRegistryEntry
GPCLRegistryEntry	getNextGroupMember(GPCLRegistryEntry oEntry) Retrieves the list of application grouped with this Head Application.
GPCLRegistryEntry	getNextReferencingApplication(GPCLRegistryEntry oEntry) Retrieve the list of applications that reference this CRELApplication's GPCLRegistryEntry
boolean	isGroupHead() Does this GPCLRegistryEntry represents a group's Head.
boolean	isGroupMember() Does this GPCLRegistryEntry represents a group's Member.
void	joinGroup(javacard.framework.AID oHead) Associates the GPCLRegistryEntry to which this GPCLRegistryEntry delegates its information parameters (i.e. head application).
void	removeFromCRELApplicationList(byte[] baAID, short offsetAID, short lengthAID) This method removes an AID from the CREL Application list referenced by this GPCLRegistryEntry
void	removeFromGroupAuthorizationList(byte[] baAID, short offsetAID, short lengthAID) This method is used to remove an AID from the Group Authorization list.
byte	setCLState(byte state) Changes the contactless life cycle state of the applet associated with this GPCLRegistryEntry.
short	setInfo(byte[] buffer, short offset, short length, short info) Update the contents of the Information associated to this GPCLRegistryEntry.
void	setPartialSelectionOrder(boolean TopBottom) Manage the GlobalPlatform registry order for partial selection priority.

Methods inherited from interface org.globalplatform.GPRegistryEntry

deregisterService, getAID, getPrivileges, getState, isAssociated, isPrivileged, registerService, setState

Field Detail

PRIVILEGE_CONTACTLESS_ACTIVATION

static final byte PRIVILEGE_CONTACTLESS_ACTIVATION

Contactless Activation privilege (18). This privilege allows

• Enable/Disable ISO 14443 interface.
• Activate/Deactivate an applet on the ISO 14443 interface .
• Managing the GlobalPlatform Registry order (for partial selection).
• Managing the GlobalPlatform Volatile Priority List.

See Also:

Constant Field Values

PRIVILEGE_CONTACTLESS_SELF_ACTIVATION

static final byte PRIVILEGE_CONTACTLESS_SELF_ACTIVATION

Self Activation privilege (19). This privilege allows an Applet to transition to ACTIVATED on the Contactless interface.

See Also:

Constant Field Values

STATE_CL_NON_ACTIVATABLE

static final byte STATE_CL_NON_ACTIVATABLE

Constant used to change the state of an applet to NON ACTIVATABLE over the contactless interface. When applet is NON ACTIVATABLE, it is also implicitly DEACTIVATED.

See Also:

Constant Field Values

STATE_CL_ACTIVATED

static final byte STATE_CL_ACTIVATED

Constant used to activate an applet on the contactless interface. An applet that is currently NON ACTIVATABLE can not be ACTIVATED.

See Also:

Constant Field Values

STATE_CL_DEACTIVATED

static final byte STATE_CL_DEACTIVATED

Constant used to deactivate an applet on the contactless interface.

See Also:

Constant Field Values

INFO_URI

static final short INFO_URI

The requested information is an URI.

See Also:

Constant Field Values

INFO_DISCRETIONARY_DATA

static final short INFO_DISCRETIONARY_DATA

The requested information is discretionary data.

See Also:

Constant Field Values

INFO_LOGO

static final short INFO_LOGO

The requested information is a LOGO.

See Also:

Constant Field Values

INFO_PROTOCOL_DATA_TYPE_A

static final short INFO_PROTOCOL_DATA_TYPE_A

The requested information is the PROTOCOL_DATA_TYPE_A.

See Also:

Constant Field Values

INFO_PROTOCOL_DATA_TYPE_B

static final short INFO_PROTOCOL_DATA_TYPE_B

The requested information is the PROTOCOL_DATA_TYPE_B.

See Also:

Constant Field Values

INFO_PROTOCOL_DATA_TYPE_F

static final short INFO_PROTOCOL_DATA_TYPE_F

The requested information is the PROTOCOL_DATA_TYPE_F.

See Also:

Constant Field Values

INFO_FAMILY_IDENTIFIER

static final short INFO_FAMILY_IDENTIFIER

The Application family identifier is a short value.

• MSB byte 1 set to 00 the LSB byte holds the AFI as defined in table 12 of ISO/IEC 14443-3.
• Other values of are reserved for proprietary use.

  See Also:

  Constant Field Values

INFO_IMPLICIT_SELECTION_PROTOCOLS

static final short INFO_IMPLICIT_SELECTION_PROTOCOLS

The supported protocol Type A, Type B or / and Type F.

Encoding of this information is a sequence of bytes representing the value(s) of one or more of the following constants.

IMPLICIT_SELECTION_TYPE_A

IMPLICIT_SELECTION_TYPE_B

IMPLICIT_SELECTION_TYPE_F If the sequence is empty, the application can be implicity selected using any of these protocol types (see definition of TLV "Assigned Protocol for Implicit Selection").

See Also:

Constant Field Values

INFO_CONTINUOUS_PROCESS

static final short INFO_CONTINUOUS_PROCESS

The Application continuous processing is a Byte value 1 Continuous Processing 0 Interleave Processing

See Also:

Constant Field Values

INFO_COUNTER_UPDATE

static final short INFO_COUNTER_UPDATE

The GPCLentry update counter. Each time a GPCLRegistryEntry information is updated this counter is incremented. Used to synchronize the CRS/CREL application list.

See Also:

Constant Field Values

INFO_DISPLAY_REQUIREMENT

static final short INFO_DISPLAY_REQUIREMENT

The GPCLRegistryEntry display on off requirement. Used to know if the application can work in display off mode.

Byte value 1 can work when Display OFF

Byte value 0 can not work when display OFF

See Also:

Constant Field Values

IMPLICIT_SELECTION_TYPE_A

static final byte IMPLICIT_SELECTION_TYPE_A

Constant indicating that the application supports contactless protocol Type A for implicit selection

See Also:

Constant Field Values

IMPLICIT_SELECTION_TYPE_B

static final byte IMPLICIT_SELECTION_TYPE_B

Constant indicating that the application supports contactless protocol Type B for implicit selection

See Also:

Constant Field Values

IMPLICIT_SELECTION_TYPE_F

static final byte IMPLICIT_SELECTION_TYPE_F

Constant indicating that the application supports contactless protocol Type F for implicit selection

See Also:

Constant Field Values

Method Detail

setCLState

byte setCLState(byte state)

Changes the contactless life cycle state of the applet associated with this GPCLRegistryEntry.

When this entry is a group member and is in STATE_CL_NON_ACTIVATABLE state then this entry follows the activation state of the Head Application when state transition of this entry is to STATE_CL_ACTIVATED or to STATE_CL_DEACTIVATED.

Only the application associated to this entry may transition to the STATE_CL_NON_ACTIVATABLE state.

The application associated to this entry, or the Application with the PRIVILEGE_CONTACTLESS_ACTIVATION privilege, or CREL Applications registered in the investigated applet's CREL list may transition this entry to the STATE_CL_DEACTIVATED

When the state transition of this entry is to STATE_CL_ACTIVATED, the caller must have

• the PRIVILEGE_CONTACTLESS_SELF_ACTIVATION privilege or
• the PRIVILEGE_CONTACTLESS_ACTIVATION privilege
• otherwise
  • The OPEN will locate the CRSApplication.
  • The OPEN will call the CRSApplication.processCLRequest(GPRegistryEntry, GPCLRegistryEntry, short)
  • The CRSApplication shall use setCLState(byte) to change the application state on the contactless interface.

The OPEN is responsible to notify all Application(s) implementing CRELApplication.notifyCLEvent(GPCLRegistryEntry, short). If the Application associated to this entry, implements the interface CLApplet and the Application is not at the origin of the request then OPEN shall notify the application by calling CLApplet.notifyCLEvent(short)

It shall be supported to change the activation state of a contactless applet irrespective of the state of the contactless front end in the handset. When the contactless functionality is enabled the OPEN shall ensure that the contactless front end is provisioned so that it reflects the configuration of the contactless applets in the OPEN.

Parameters:

state - requested Availability state on Contactless interface The possible state are

STATE_CL_ACTIVATED

STATE_CL_DEACTIVATED

STATE_CL_NON_ACTIVATABLE

Returns:

the resulting Availablity state on Contactless interface.

Throws:

javacard.framework.ISOException - with reason

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller does not have enough privileges.
• ISO7816.SW_WRONG_DATA if the application cannot be activated on the contactless interface because of conflicting RF parameters.
• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the requested Availability state transition is not valid.

See Also:

GPRegistryEntry

getCLState

byte getCLState()

This method returns the contactless life cycle state of application.

Returns:

byte value of contactless state

STATE_CL_ACTIVATED

STATE_CL_DEACTIVATED

STATE_CL_NON_ACTIVATABLE

getInfo

short getInfo(byte[] buffer,
              short offset,
              short info)

Returns the contents of the Application Information entry in the GlobalPlatform registry.

Parameters:

buffer - where requested information shall be written. For the coding of the data see the documentation of the constants INFO_XX.

offset - within buffer, where requested information shall be written.

info - is any constant with name INFO_XX which is defined in this interface.

Returns:

(offset + length of data written in buffer)

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED if the caller
  • is not the Application itself, and
  • does not have the GPRegistryEntry.PRIVILEGE_GLOBAL_REGISTRY privilege, and
  • is not a Security Domain that is directly or indirectly associated to the Application identified by this entry, and
  • is not a CREL Application registered in the CREL list of the Application identified by this entry.
• ISO7816.SW_WRONG_DATA if the value of info is unknown.
• ISO7816.SW_RECORD_NOT_FOUND if the info is not present.

ArrayIndexOutOfBoundsException - if storing the Application Information bytes would cause access outside array bounds or the offset is negative.

NullPointerException - if buffer is null

setInfo

short setInfo(byte[] buffer,
              short offset,
              short length,
              short info)

Update the contents of the Information associated to this GPCLRegistryEntry.

Parameters:

buffer - contains the updated information. For the coding of the data see the documentation of the constants INFO_XX.

offset - within buffer, where updated information can be found

length - of the updated information

info - is any constant with name INFO_XX which is defined in this interface.

Returns:

(offset + length)

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED if the caller is not
  • the Associated Security Domain
  • or the Application itself
• ISO7816.SW_WRONG_DATA if the value of info is unknown.

ArrayIndexOutOfBoundsException - if storing the Application Information bytes would cause access outside array bounds or the offset is negative.

NullPointerException - if buffer is null

getNextConflictingApplication

GPCLRegistryEntry getNextConflictingApplication(GPCLRegistryEntry oEntry)

This method allows iteration over the currently activated contactless applets that would conflict if the applet associated with this entry was activated.

Parameters:

oEntry -

if oEntry is null, this method returns the first Entry representing the first conflicting application.

If the list is empty, the method shall return null.

If oEntry is not null, and represents a conflicting application, this method retrieves the next conflicting application following oEntry, otherwise it shall return null.

If oEntry points to the last conflicting application, the method shall return null.

Returns:

the reference to the contactless application which would cause a conflict. The value null is returned if no contactless application is conflicting or the end of the list has been reached.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED if caller does not have the PRIVILEGE_CONTACTLESS_ACTIVATION privilege.

joinGroup

void joinGroup(javacard.framework.AID oHead)

Associates the GPCLRegistryEntry to which this GPCLRegistryEntry delegates its information parameters (i.e. head application).

Parameters:

oHead - Head Application's AID

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED
  • if the caller is not the Application itself or
  • is associated to another Head Application or
  • is a Head application

getNextGroupMember

GPCLRegistryEntry getNextGroupMember(GPCLRegistryEntry oEntry)

Retrieves the list of application grouped with this Head Application.

Parameters:

oEntry - search

• If this does not reference a Head Application, this method returns null. Otherwise,
• if oEntry is null, this method returns the first Entry representing the first member of the Application Group.
• If the list is empty, the method shall return null.
• If oEntry is not null, and is a member of the group, this method retrieves the next Entry following oEntry belonging to the same Application Group, otherwise it shall return null.
• If oEntry points to the last member of the group, the method shall return null.
• The caller must have the PRIVILEGE_CONTACTLESS_ACTIVATION Contactless Activation

Returns:

the Entry that is part of the group or null if no group or end of group list

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED
  • if the caller has not PRIVILEGE_CONTACTLESS_ACTIVATION and
  • is not a CRELApplication associated to this entry

addToGroupAuthorizationList

void addToGroupAuthorizationList(byte[] baAID,
                                 short offsetAID,
                                 short lengthAID)

This method is used to add an AID to the Group Authorization list.

Parameters:

baAID - contains the AID value to manage

offsetAID - start offset of the AID value

lengthAID - length of the AID value

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED
  • if the caller application is already associated to a Head Application, or
  • if the caller application is neither the application itself or the associated Security Domain.

removeFromGroupAuthorizationList

void removeFromGroupAuthorizationList(byte[] baAID,
                                      short offsetAID,
                                      short lengthAID)

This method is used to remove an AID from the Group Authorization list.

Parameters:

baAID - contains the AID value to removed

offsetAID - start offset of the AID value

lengthAID - length of the AID value

Throws:

ISOException - with reason

ISO7816.SW_CONDITION_NOT_SATISFIED if the caller application is neither the application itself or the associated Security Domain.

setPartialSelectionOrder

void setPartialSelectionOrder(boolean TopBottom)

Manage the GlobalPlatform registry order for partial selection priority. If this GPCLentry is a head of a group, group members are moved in the same order.

Parameters:

TopBottom -

• true: the GPRegistryEntry of this entry, becomes the first selected on partial selection.
• false:the GPRegistryEntry of this entry becomes the last selected on partial selection.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED if the caller has not PRIVILEGE_CONTACTLESS_ACTIVATION

getNextCRELApplication

GPCLRegistryEntry getNextCRELApplication(GPCLRegistryEntry oEntry)

Retrieve the list of CREL applications referenced by this GPCLRegistryEntry

Parameters:

oEntry - search

• if oEntry is null, this method returns the first Entry representing the first CRELApplication.
• If the list is empty, the method shall return null.
• If oEntry is not null, and represents a CRELApplication CRELApplication reference by this GPCLRegistryEntry, this method retrieves the next Entry following oEntry referenced by this , otherwise it shall return null.
• If oEntry points to the last CRELApplication's GPCLRegistryEntry, the method shall return null.

Returns:

• next entry referencing a CREL application.
• null, if no more entry.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED if the caller has not PRIVILEGE_CONTACTLESS_ACTIVATION

addToCRELApplicationList

void addToCRELApplicationList(byte[] baAID,
                              short offsetAID,
                              short lengthAID)

This method add an AID to the CREL Application list referenced by this GPCLRegistryEntry

Parameters:

baAID - contains the CREL Application's AID value to manage

offsetAID - start offset of the CREL Application's AID value

lengthAID - length of the AID value

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_SATISFIED if
  • is not the Security Domain directly associated with the applet being investigated, and
  • is not the investigated applet itself.

removeFromCRELApplicationList

void removeFromCRELApplicationList(byte[] baAID,
                                   short offsetAID,
                                   short lengthAID)

This method removes an AID from the CREL Application list referenced by this GPCLRegistryEntry

Parameters:

baAID - contains the CREL Application's AID value to manage

offsetAID - start offset of the CREL Application's AID value

lengthAID - length of the AID value

Throws:

ISOException - with reason

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if
  • is not the Security Domain directly associated with the applet being investigated, and
  • is not the investigated applet itself.

getNextReferencingApplication

GPCLRegistryEntry getNextReferencingApplication(GPCLRegistryEntry oEntry)

Retrieve the list of applications that reference this CRELApplication's GPCLRegistryEntry

Parameters:

oEntry - search

• if oEntry is null, this method returns the first Entry representing the first GPCLRegistryEntry, that references this CRELApplication
• If the list is empty, the method shall return null.
• If oEntry is not null, and represents a GPCLRegistryEntry that references this CRELApplication this method retrieves the next Entry following oEntry referencing this CRELApplication, otherwise it shall return null.
• If oEntry points to the last CRELApplication's GPCLRegistryEntry, the method shall return null.
• The caller shall implement CRELApplication interface.

Returns:

• next entry referencing this CRELApplication.
• null, if no more entry.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_STATISFIED if the caller does not implement CRELApplication interface.

isGroupHead

boolean isGroupHead()

Does this GPCLRegistryEntry represents a group's Head.

Returns:

true true if this Application is a Group Head, false otherwise.

Throws:

ISOException - with reason

ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller has not GPRegistryEntry.PRIVILEGE_GLOBAL_REGISTRY

isGroupMember

boolean isGroupMember()

Does this GPCLRegistryEntry represents a group's Member.

Returns:

true is this Application is a if this Application is a Group Member, false if this is a standalone Application.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller has not GPRegistryEntry.PRIVILEGE_GLOBAL_REGISTRY